Purpose

The purpose of the present document is to provide an installation guide and to describe the mode of operation of the Auxiliary Data Conversion System Next Generation (ADCSng) and a summary of its main functionalities. After reading this document the user should be able to install, work with and fully understand the software package.

Running ADCSng in a nutshell

1. Obtain ADCSng from BitBucket: https://repos.cosmos.esa.int/socci/projects/SPICE/repos/adcsng/

2. Install from top level directory with "pip3 install -e ."

3. Generate an ADCSng configuration file as from adcsng/adcsng/tests/bc/bepicolombo.json

4. Generate the appropriate directory structure as derived from the configuration file

5. Obtain and install your SPICE Kernel Dataset: https://repos.cosmos.esa.int/socci/projects/SPICE_KERNELS

6. Run with "adcsng yourconfig.json"

Overview

Auxiliary data are those that help scientists and engineers to determine the location and orientation of the spacecraft, when and how an instrument was acquiring scientific data. These data also help to determine what other relevant events were occurring on the spacecraft or ground that might affect the interpretation of the scientific observation or the S/C systems performance. Software applications are required to know what were the location, size, shape and orientation of the observed target in addition to these auxiliary data. Almost all NASA and ESA planetary missions have embraced the use of the SPICE system for ancillary data archiving and for science data analysis. Although the Flight Dynamics Division provides software to read the position and orientation files of the orbiters, most of the Principal Investigators (PI) have pointed out their interest in having all the auxiliary data distributed in SPICE format.

The ESA SPICE Service (ESS) of the Cross Mission Support Office is responsible for supporting the ESOC auxiliary data transformation into SPICE kernels and the distribution of these files to the instrument teams using the public network. NASA’s Planetary Data System discipline node NAIF (Navigational Ancillary Information Facility) is responsible for designing a transformation software tool to generate spacecraft orbit and attitude SPICE kernels. The ESS, helped by the individual instrument and FDy teams, the SGSs, and, in some missions, supported by NAIF, design and support all the necessary instrument, spacecraft and timing kernels.

Applicable Documents

Reference Documents

Hardware and Software requirements

ADCSng is a Python 3.6.x package that uses FORTRAN 77 and FORTRAN 90 applications and a set of standard Python libraries. ADCSng is meant to interact with different nodes: SGS Uplink and Downlink sub-systems, the ESA SPICE FTP Server and the NAIF FTP Server.

ADCsng is designed to work with UNIX systems namely with Linux and with MacOS. The hardware requirements are minimal and any modern computer/server will suffice. The software is able to run for example in a minimal CentOS 7 Virtual Machine:

• Architecture: x86_64 (64 bits)

• Memory: 1GB/logical CPU

• Disk space: 10GB

The software requirements are the following:

• Python 3.6 or higher

• Python packages:

  • numpy >= 1.8.0

  • pytest >= 2.9.0

  • pandas > 0.17.1

  • html-testRunner

• gcc

• libgfortran

• Git (possibly, for the obtention of SPICE Kernel Datasets)

Please note that the FORTRAN applications are already compiled and therefore the user should not compile and link them. Nevertheless this is possible since the source code is distributed with ADCSng, the only remaining part would be to link them with the SPICELIB library of the SPICE Toolkit. The compilation of these applications is out of the scope of this SUM and any interested user is encourage to try by himself or to contact the author.

Obtaining the Software

Configuration

The next step to use ADCSng is to configure it. ADCSng has two levels of configuration:

• User configuration

• Developer configuration (placed under the adcsng/adcsng/config directory)

As a user you only need to take care of the user configuration. the user configuration has to be edited and prepared by the user. It consists of a JSON file and an example from the test directory of ADCSng can be used as baseline (adcsng/adcsng/tests/bc/bepicolombo.json). Any name can be provided to the configuration file, the file extension has to be *.json. The configuration file will determine the directory structure that you need to setup for ADCSng. The recommendation is to create a directory out of the ADCSng directory structure and to create one per intended ADCSng execution/project.

The following table describes all the available configuration items (please note that all the items are strings):

Once the configuration file has been generated it can be placed anywhere in your computer, it is recommended to put it in the same directory level as where you will define the directory structure of your ADCSng configuration. What follows is an example of an ADCSng configuration file:

If we consider the previous configuration file we could have a directory structure as follows:

Remember that you need to generate this directory structure for ADCSng will not generate it for you.

Log format

The log format per line is as follows (Python syntax):

This translates into the following columns: Time | Information Level | Module logging | Log message (please note that prompted log only includes the Log message).

There are four information levels:

1. INFO : Log information of all kinds, nothing to worry about.

2. WARNING : A foreseen/predictable action by the pipeline (input processing, present files) nothing to worry about but sometimes worth checking.

3. ERROR : Something which should not have happened and that the developer might want to look into but that did not interrupt the execution.

4. CRITICAL : Something bad which interrupted the execution and that will most probably translate into human intervention either from the user or a bug-fix from the developer.

What follows is a log example:

The ADCSng lock file

When ADCSng is executed, ADCSng works/modifies the source and output directories. Due to this parallel runs of ADCSng on the same directory structure could lead into disaster. ADCSng is triggered by a daemon (crontab) in the SPICE operational server and although in principle executions are planned in such a way this event does not happen, if multiple long orbit files were to be processed, executions might overlap.

The solution has been to implement a locking mechanism. When ADCSng is executed, it will generate an empty lock file as per configuration. If no lock file is provided in the configuration, then the default will be to write it in the directory where ADCSng is being executed with the following name: adcsng_mission.lock

The lock file will be automatically removed at the end of an execution even if it is a failed execution. If a lock file is present when a new execution is requested, ADCSng will not run and if emails are enabled, it will send an e-mail to the developer indicating so.